TYRO.IClientWithUI Class

Uses

TYRO.BaseIClient

Module: TYRO

Overview

The Tyro IClient with UI provides a simpler path for a POS to integrate with a Tyro terminal. The regular IClient allows a POS to have full control over presentation of status messages and questions but requires a POS vendor to write more code. The IClient with UI allows a POS to start a transaction and just wait for the transaction result. See the sequence diagrams in the TYRO module description.

To use the Tyro iClient a POS needs to include the following library:

<script src="https://iclient.tyro.com/iclient-with-ui-v1.js" type="text/javascript"></script>

Replace iclient.tyro.com with one of the following URLs for development/testing:

iclienttest.tyro.com connects to the integration server simulator which does not require a physical payment terminal
iclientpreprod.tyro.com connects a test system that can only be used with a physical terminal

Configuration

Configuration for the Tyro iClient can be found at:

https://iclient.tyro.com/configuration.html

A merchant can use this page to:

pair their terminal with their browser
test their terminal connection

Replace iclient.tyro.com with one of the following URLs for development/testing:

iclientsimulator.test.tyro.com connects to the integration server simulator which does not require a physical payment terminal
iclient.test.tyro.com connects a test system that can only be used with a physical terminal

For pairing a POS and terminal, the Tyro configuration page can be used. The alternative URLs above should be used for the test and pre production environments.

A working example of using the iclient library to make a purchase can be found here.

Constructor

`TYRO.IClientWithUI`

(

apiKey
posProductData

)

Parameters:

apiKey String

The API key provided by Tyro.
posProductData Object

An object containing the following properties (check with Tyro in case of any questions):
- posProductVendor String
  
  Name of your company.
- posProductName String
  
  Name of your product.
- posProductVersion String
  
  Version of your product.

Example:

var iclient = new TYRO.IClientWithUI("apiKey", {posProductVendor: "Name of your company", posProductName: "Name of your product", posProductVersion: "Version of your product"});

Index
Methods

Item Index

Methods

addTip
cancelHealthPointClaim
closeTab
completePreAuth
continueLastTransaction
healthpointReconciliationReport
initiateBulkBillEasyclaim
initiateFullyPaidEasyclaim
initiateHealthPointClaim
initiateIncrementPreAuth
initiateOpenPreAuth
initiateOpenTab
initiatePartPaidEasyclaim
initiatePurchase
initiateRefund
manualSettlement
pairTerminal
reconciliationReport
voidPreAuth
voidTab

Methods

`addTip`

(

completionReference
tipAmount
responseReceivedCallback

)

Inherited from TYRO.BaseIClient:

Add a tip to a previous purchase (initiatePurchase).

Parameters:

completionReference String

Transaction identifier from the original transaction.
tipAmount String

The tip amount to add in cents.
responseReceivedCallback Function
Invoked to indicate success or failure. Called with a single Object containing the following properties:
- resultString
  One of the following values: success, failure.
- messageString
  Message to show the merchant.

Example:

// to add a $3.00 tip to a transaction with completion reference 543123
iclient.addTip("543123", "300", yourPosCode.handleResponse);

`cancelHealthPointClaim`

(

requestParams
transactionCallbacks

)

Tell the terminal to cancel a completed HealthPoint claim.

Parameters:

requestParams Object

An object containing the following properties:
- providerId String
  
  The 8 character id of the provider attending the patient.
- serviceType String
  
  The 1 alphabetic character representing the category of service.
- claimItemsCount String
  
  The total number of claim items.
- totalClaimAmount Int
  
  The total amount of all claim items in cents.
- claimItems String
  
  A list of claim items as a JSON array.
- refTag String
  
  The reference tag returned in the original claim's final transaction status response.
- [mid] Int optional
  
  Override the configured mid for multi-merchant terminals or if your browser does not support local storage.
- [tid] Int optional
  
  Override the configured tid for multi-merchant terminals or if your browser does not support local storage.
- [integrationKey] String optional
  
  Supply the integration key if your browser does not support local storage.
transactionCallbacks Object

The set of callback functions to provide feedback and the transaction result:
- transactionCompleteCallback Function
  
  See transaction complete callback.

Example:

// to initiate a cancel of a completed healthpoint claim with two claim items totaling $250
iclient.cancelHealthPointClaim({providerId: "2147661H", serviceType: "D", claimItemsCount: "2", totalClaimAmount: "25000", refTag: "0960001", claimItems: [
        {
            "claimAmount": "10000",
            "serviceCode": "00001",
            "description": "SKULL XRAY",
            "serviceReference": "01",
            "patientId": "02",
            "serviceDate": "20131010"
        },
        {
            "claimAmount": "15000",
            "serviceCode": "00001",
            "description": "SKULL XRAY",
            "serviceReference": "01",
            "patientId": "02",
            "serviceDate": "20140508"
        }
    ]}, {
   transactionCompleteCallback: yourPosCode.handleComplete
});

`closeTab`

(

completionReference
amount
responseReceivedCallback

)

Inherited from TYRO.BaseIClient:

Close a previously opened bar tab (initiateOpenTab) with a final amount. The customer will be charged.

Parameters:

completionReference String

Transaction identifier from the original transaction.
amount String

The final amount to charge the customer.
responseReceivedCallback Function
Invoked to indicate success or failure. Called with a single Object containing the following properties:
- resultString
  One of the following values: success, failure.
- messageString
  Message to show the merchant.

Example:

// to close the tab with completion reference 543123 and bill a customer $120.01
iclient.closeTab("543123", "12001", yourPosCode.handleResponse);

`completePreAuth`

(

requestParams
responseReceivedCallback

)

Inherited from TYRO.BaseIClient:

Close a previously opened preAuth (initiateOpenPreAuth) with a final amount. The customer will be charged.

Parameters:

requestParams Object

An object containing the following properties:
- completionReference String
  
  Transaction identifier from the original transaction.
- amount String
  
  The final amount to charge the customer.
- [integrationKey] String optional
  
  Supply the integration key if your browser does not support local storage.
- [mid] Int optional
  
  Override the configured mid for multi-merchant terminals.
- [tid] Int optional
  
  Override the configured tid for multi-merchant terminals.
responseReceivedCallback Function
Invoked to indicate success or failure. Called with a single Object containing the following properties:
- resultString
  One of the following values: success, failure.
- messageString
  Message to show the merchant.

Example:

// to close the preAuth with completion reference 543123 and bill a customer $120.01
iclient.completePreAuth({amount: "12001", completionReference: "543123"}, yourPosCode.handleResponse);

`continueLastTransaction`

(

transactionCallbacks

)

Tell the terminal to continue the last transaction.

Parameters:

transactionCallbacks Object

See the transaction callbacks description for initiatePurchase.

Example:

// comtinueLastTransaction
iclient.continueLastTransactioon({
   questionCallback: yourPosCode.handleQuestionChanged,
   statusMessageCallback: yourPosCode.handleStatusMessageChanged,
   receiptCallback: yourPosCode.handleReceiptChanged,
   transactionCompleteCallback: yourPosCode.handleTransactionCompleted
});

`healthpointReconciliationReport`

(

requestParams
responseReceivedCallback

)

Inherited from TYRO.BaseIClient:

Retrieve a payments or claims HealthPoint reconciliation report.

Parameters:

requestParams Object

An object containing the following properties:
- reconDate String
  
  The reporting date in format yyyyMMdd.
- reportType String
  
  The report type. Valid values are payments and claims.
- integrationKey String
  
  Supply the integration key if your browser does not support local storage.
responseReceivedCallback Function
Callback to return the report or error message. Called with a single Object containing the following properties:
- resultString
  One of the following values: success, failure.
- dataString
  The report in xml format.
- errorString
  An error message to show the merchant. Only present when result is failure.

Example:

     // to retrieve the HealthPoint payments report for 25th December 2012
     iclient.healthpointReconciliationReport({
        reportType: "payments",
        reconDate "20121225"
     }, yourPosCode.handleResponse);

`initiateBulkBillEasyclaim`

(

requestParams
transactionCallbacks

)

Tell the terminal to start a bulk billed Easyclaim request.

Parameters:

requestParams Object

An object containing the following properties:
- payload String
  
  The Easyclaim payload that is forwarded to Medicare.
- rightsAssigned Boolean
  
  Whether rights have already been assigned
- [mid] Int optional
  
  Override the configured mid for multi-merchant terminals or if your browser does not support local storage.
- [tid] Int optional
  
  Override the configured tid for multi-merchant terminals or if your browser does not support local storage.
- [integrationKey] String optional
  
  Supply the integration key if your browser does not support local storage.
transactionCallbacks Object

The set of callback functions to provide feedback and the transaction result:
- transactionCompleteCallback Function
  
  See transaction complete callback.

Example:

iclient.initiateBulkBillEasyclaim({payload: "<ns1:patienteClaimingRequest>...</ns1:patienteClaimingRequest>", rightsAssigned: true}, {
   transactionCompleteCallback: yourPosCode.handleComplete
});

`initiateFullyPaidEasyclaim`

(

requestParams
transactionCallbacks

)

Tell the terminal to start a fully paid Easyclaim request.

Parameters:

requestParams Object

An object containing the following properties:
- payload String
  
  The Easyclaim payload that is forwarded to Medicare.
- [mid] Int optional
  
  Override the configured mid for multi-merchant terminals or if your browser does not support local storage.
- [tid] Int optional
  
  Override the configured tid for multi-merchant terminals or if your browser does not support local storage.
- [integrationKey] String optional
  
  Supply the integration key if your browser does not support local storage.
transactionCallbacks Object

The set of callback functions to provide feedback and the transaction result:
- transactionCompleteCallback Function
  
  See transaction complete callback.

Example:

iclient.initiateFullyPaidEasyclaim({payload: "<ns1:patienteClaimingRequest>...</ns1:patienteClaimingRequest>"}, {
   transactionCompleteCallback: yourPosCode.handleComplete
});

`initiateHealthPointClaim`

(

requestParams
transactionCallbacks

)

Tell the terminal to start a HealthPoint claim.

Parameters:

requestParams Object

An object containing the following properties:
- providerId String
  
  The 8 character id of the provider attending the patient.
- serviceType String
  
  The 1 alphabetic character representing the category of service.
- claimItemsCount String
  
  The total number of claim items.
- totalClaimAmount Int
  
  The total amount of all claim items in cents.
- claimItems String
  
  A list of claim items as a JSON array.
- [mid] Int optional
  
  Override the configured mid for multi-merchant terminals or if your browser does not support local storage.
- [tid] Int optional
  
  Override the configured tid for multi-merchant terminals or if your browser does not support local storage.
- [integrationKey] String optional
  
  Supply the integration key if your browser does not support local storage.
transactionCallbacks Object

The set of callback functions to provide feedback and the transaction result:
- transactionCompleteCallback Function
  
  See transaction complete callback.

Example:

// to initiate a dental claim with two claim items totaling $250
iclient.initiateHealthPointClaim({providerId: "2147661H", serviceType: "D", claimItemsCount: "2", totalClaimAmount: "25000", claimItems: [
        {
            "claimAmount": "10000",
            "serviceCode": "00001",
            "description": "SKULL XRAY",
            "serviceReference": "01",
            "patientId": "02",
            "serviceDate": "20131010"
        },
        {
            "claimAmount": "15000",
            "serviceCode": "00001",
            "description": "SKULL XRAY",
            "serviceReference": "01",
            "patientId": "02",
            "serviceDate": "20140508"
        }
    ]}, {
   transactionCompleteCallback: yourPosCode.handleComplete
});

`initiateIncrementPreAuth`

(

requestParams
responseReceivedCallback

)

Send incremental pre-auth to increase the amount of previously opened pre-auth (initiateOpenPreAuth) with an incremental amount.

Parameters:

requestParams Object

An object containing the following properties:
- completionReference String
  
  Transaction identifier from the original transaction.
- amount String
  
  The incremental amount to increment the pre-auth amount.
- [integrationKey] String optional
  
  Supply the integration key if your browser does not support local storage.
- [mid] Int optional
  
  Override the configured mid for multi-merchant setup if your browser does not support local storage.
- [tid] Int optional
  
  Override the configured tid for multi-merchant setup if your browser does not support local storage.
- [transactionId] String optional
  
  Supply a transaction Id to be used for the transaction.
responseReceivedCallback Function

See the transaction callbacks description for initiateIncrementPreAuth.

Example:

// to increment the preAuth by $50.00 with completion reference 543123.
iclient.initiateIncrementPreAuth({amount: "5000", completionReference: "543123"}, yourPosCode.handleResponse);

`initiateOpenPreAuth`

(

requestParams
transactionCallbacks

)

Tell the terminal to start an open preAuth transaction.

Parameters:

requestParams Object

An object containing the following properties:
- amount String
  
  The preAuth limit (maximum amount to charge the customer) in cents.
- integratedReceipt Boolean
  
  indicate whether receipts will be printed on the POS (true) or on the terminal (false).
- [mid] Int optional
  
  Override the configured mid for multi-merchant terminals or if your browser does not support local storage.
- [tid] Int optional
  
  Override the configured tid for multi-merchant terminals or if your browser does not support local storage.
- [integrationKey] String optional
  
  Supply the integration key if your browser does not support local storage.
- [transactionId] String optional
  
  Supply a transaction Id to be used for the transaction.
transactionCallbacks Object

See the transaction callbacks description for initiatePurchase.

Example:

// open preAuth for $10.00
iclient.initiateOpenPreAuth({amount: "1000", integratedReceipt: false}, {
    receiptCallback: yourPosCode.handleReceipt,
    transactionCompleteCallback: yourPosCode.handleComplete
});

`initiateOpenTab`

(

requestParams
transactionCallbacks

)

Tell the terminal to start an open tab transaction.

Parameters:

requestParams Object

An object containing the following properties:
- amount String
  
  The tab limit (maximum amount to charge the customer) in cents.
- integratedReceipt Boolean
  
  indicate whether receipts will be printed on the POS (true) or on the terminal (false).
- [mid] Int optional
  
  Override the configured mid for multi-merchant terminals or if your browser does not support local storage.
- [tid] Int optional
  
  Override the configured tid for multi-merchant terminals or if your browser does not support local storage.
- [integrationKey] String optional
  
  Supply the integration key if your browser does not support local storage.
- [transactionId] String optional
  
  Supply a transaction Id to be used for the transaction.
transactionCallbacks Object

See the transaction callbacks description for initiatePurchase.

Example:

// open tab for $10.00
iclient.initiateOpenTab({amount: "1000", integratedReceipt: false}, {
    receiptCallback: yourPosCode.handleReceipt,
    transactionCompleteCallback: yourPosCode.handleComplete
});

`initiatePartPaidEasyclaim`

(

requestParams
transactionCallbacks

)

Tell the terminal to start a part paid Easyclaim request.

Parameters:

requestParams Object

An object containing the following properties:
- payload String
  
  The Easyclaim payload that is forwarded to Medicare.
- [mid] Int optional
  
  Override the configured mid for multi-merchant terminals or if your browser does not support local storage.
- [tid] Int optional
  
  Override the configured tid for multi-merchant terminals or if your browser does not support local storage.
- [integrationKey] String optional
  
  Supply the integration key if your browser does not support local storage.
transactionCallbacks Object

The set of callback functions to provide feedback and the transaction result:
- transactionCompleteCallback Function
  
  See transaction complete callback.

Example:

iclient.initiatePartPaidEasyclaim({payload: "<ns1:patienteClaimingRequest>...</ns1:patienteClaimingRequest>"}, {
   transactionCompleteCallback: yourPosCode.handleComplete
});

`initiatePurchase`

(

requestParams
transactionCallbacks

)

Tell the terminal to start a purchase transaction.

Parameters:

requestParams Object

An object containing the following properties:
- amount String
  
  The purchase amount (amount to charge the customer) in cents.
- [cashout] String optional
  
  Cash out amount in cents.
- integratedReceipt Boolean
  
  indicate whether receipts will be printed on the POS (true) or on the terminal (false).
- integratedReceiptWidth String
  
  The width of the integrated receipt in number of characters as a String.
- [mid] Int optional
  
  Override the configured mid for multi-merchant terminals or if your browser does not support local storage.
- [tid] Int optional
  
  Override the configured tid for multi-merchant terminals or if your browser does not support local storage.
- [integrationKey] String optional
  
  Supply the integration key if your browser does not support local storage.
- [transactionId] String optional
  
  Supply a transaction Id to be used for the transaction.
- [healthpointTransactionId] String optional
  
  The integrated transaction ID of the original HealthPoint Claim (used for gap payments).
- [enableSurcharge] Boolean optional
  
  Apply a surcharge to this transaction (if the card used attracts a surcharge).
- [requestCardToken] Boolean optional
  
  Request a token representing the card used for the current purchase.
transactionCallbacks Object

The set of callback functions to provide feedback and the transaction result:
- [receiptCallback] Function optional
  
  See receipt callback.
- transactionCompleteCallback Function
  
  See transaction complete callback.

Example:

// purchase for $10.00
iclient.initiatePurchase({amount: "1000", integratedReceipt: false}, {
   receiptCallback: yourPosCode.handleReceipt,
   transactionCompleteCallback: yourPosCode.handleComplete
});

`initiateRefund`

(

requestParams
transactionCallbacks

)

Tell the terminal to start a refund transaction.

Parameters:

requestParams Object

An object containing the following properties:
- amount String
  
  The refund amount (amount to be given to the customer) in cents.
- integratedReceipt Boolean
  
  indicate whether receipts will be printed on the POS (true) or on the terminal (false).
- integratedReceiptWidth String
  
  The width of the integrated receipt in number of characters as a String.
- [mid] Int optional
  
  Override the configured mid for multi-merchant terminals or if your browser does not support local storage.
- [tid] Int optional
  
  Override the configured tid for multi-merchant terminals or if your browser does not support local storage.
- [integrationKey] String optional
  
  Supply the integration key if your browser does not support local storage.
- [transactionId] String optional
  
  Supply a transaction Id to be used for the transaction.
transactionCallbacks Object

See the transaction callbacks description for initiatePurchase.

Example:

// refund for $10.00
iclient.initiateRefund({amount: "1000", integratedReceipt: false}, {
    receiptCallback: yourPosCode.handleReceipt,
    transactionCompleteCallback: yourPosCode.handleComplete
});

`manualSettlement`

(

responseReceivedCallback
options

)

Inherited from TYRO.BaseIClient:

Manually settle the terminal: close off reporting for the day.

Parameters:

responseReceivedCallback Function
Called with a single Object containing the following properties:
- resultString
  One of the following values: success, failure.
- messageString
  Message to show the merchant.
- currentTerminalBusinessDayString
  Current reporting day after settlement request. Only returned if result is success. Format dd/MM/yyyy.
options Object

An object containing the following properties:
- [mid] Int optional
  
  Override the configured mid for multi-merchant terminals or if your browser does not support local storage.
- [tid] Int optional
  
  Override the configured tid for multi-merchant terminals or if your browser does not support local storage.
- [integrationKey] String optional
  
  Supply the integration key if your browser does not support local storage.

Example:

// to close the current reporting day
iclient.manualSettlement(yourPosCode.handleResponse);

`pairTerminal`

(

mid
tid
responseReceivedCallback

)

Perform the POS side of pairing (shared secret exchange) with a terminal.

Parameters:

mid String

Tyro Merchant ID (MID)
tid String

Tyro Terminal ID (TID)
responseReceivedCallback Function
Callback invoked to indicate status of pairing. Called with the following parameters:
- responseObject
  An object consisting of:
  - statusString
    One of the following values: inProgress, success, failure.
    If inProgress more responses will follow.
  - messageString
    Text to show the merchant.
  - integrationKeyString
    Integration key to be used when transacting.

Example:

// to perform the POS side of pairing for the terminal identified by (MID 2, TID 1)
iclient.pairTerminal("2", "1", yourPosCode.handleResponse);

`reconciliationReport`

(

requestParams
responseReceivedCallback

)

Inherited from TYRO.BaseIClient:

Retrieve a summary or detail reconciliation report.

Parameters:

requestParams Object

An object containing the following properties:
- terminalBusinessDay String
  
  The reporting date in format yyyyMMdd.
- type String
  
  The report type. Valid values are summary and detail.
- format String
  
  The report format. Valid values are txt and xml. The txt version is pre-formatted in a monospaced font.
- [integrationKey] String optional
  
  Supply the integration key if your browser does not support local storage.
- [mid] Int optional
  
  Override the configured mid for multi-merchant terminals.
- [tid] Int optional
  
  Override the configured tid for multi-merchant terminals.
responseReceivedCallback Function
Callback to return the report or error message. Called with a single Object containing the following properties:
- resultString
  One of the following values: success, failure.
- formatString
  The request parameter format is passed back for convenience.
- typeString
  The request parameter type is passed back for convenience.
- dataString
  The report. Pre-formatted text when format is txt. Parsable xml when format xml.
- errorString
  An error message to show the merchant. Only present when result is failure.

Example:

// to retrieve the pre-formatted detail report for 25th December 2012
iclient.reconciliationReport({
   type: "detail",
   terminalBusinessDay "20121225"
   format: "txt"
}, yourPosCode.handleResponse);

`voidPreAuth`

(

requestParams
responseReceivedCallback

)

Inherited from TYRO.BaseIClient:

Void a previously opened preAuth (initiateOpenPreAuth). This discards the hold on funds in the customer's account.

Parameters:

requestParams Object

An object containing the following properties:
- completionReference String
  
  Transaction identifier from the original transaction.
- [integrationKey] String optional
  
  Supply the integration key if your browser does not support local storage.
- [mid] Int optional
  
  Override the configured mid for multi-merchant terminals.
- [tid] Int optional
  
  Override the configured tid for multi-merchant terminals.
responseReceivedCallback Function
Invoked to indicate success or failure. Called with a single Object containing the following properties:
- resultString
  One of the following values: success, failure.
- messageString
  Message to show the merchant.

Example:

// to void a preAuth with completion reference 543123
iclient.voidPreAuth({completionReference: "543123"}, yourPosCode.handleResponse);

`voidTab`

(

completionReference
responseReceivedCallback

)

Inherited from TYRO.BaseIClient:

Void a previously opened bar tab (initiateOpenTab). This discards the hold on funds in the customer's account.

Parameters:

completionReference String

Transaction identifier from the original transaction.
responseReceivedCallback Function
Invoked to indicate success or failure. Called with a single Object containing the following properties:
- resultString
  One of the following values: success, failure.
- messageString
  Message to show the merchant.

Example:

// to void a bar tab with completion reference 543123
iclient.voidTab("543123", yourPosCode.handleResponse);

APIs

TYRO.IClientWithUI Class

Overview

Configuration

Constructor

TYRO.IClientWithUI

Parameters:

Example:

Item Index

Methods

Methods

addTip

Parameters:

Example:

cancelHealthPointClaim

Parameters:

Example:

closeTab

Parameters:

Example:

completePreAuth

Parameters:

Example:

continueLastTransaction

Parameters:

Example:

healthpointReconciliationReport

Parameters:

Example:

initiateBulkBillEasyclaim

Parameters:

Example:

initiateFullyPaidEasyclaim

Parameters:

Example:

initiateHealthPointClaim

Parameters:

Example:

initiateIncrementPreAuth

Parameters:

Example:

initiateOpenPreAuth

Parameters:

Example:

initiateOpenTab

Parameters:

Example:

initiatePartPaidEasyclaim

Parameters:

Example:

initiatePurchase

Parameters:

Example:

initiateRefund

Parameters:

Example:

manualSettlement

Parameters:

Example:

pairTerminal

Parameters:

Example:

reconciliationReport

Parameters:

Example:

voidPreAuth

Parameters:

Example:

voidTab

Parameters:

Example:

`TYRO.IClientWithUI`

`addTip`

`cancelHealthPointClaim`

`closeTab`

`completePreAuth`

`continueLastTransaction`

`healthpointReconciliationReport`

`initiateBulkBillEasyclaim`

`initiateFullyPaidEasyclaim`

`initiateHealthPointClaim`

`initiateIncrementPreAuth`

`initiateOpenPreAuth`

`initiateOpenTab`

`initiatePartPaidEasyclaim`

`initiatePurchase`

`initiateRefund`

`manualSettlement`

`pairTerminal`

`reconciliationReport`

`voidPreAuth`

`voidTab`